System explainer
Traces
Traces is a platform for capturing, sharing, discovering, and discussing traces — recordings of real sessions with AI coding agents such as Claude Code, Cursor, Codex, and a dozen others. A developer runs one command and the conversation that produced a piece of code becomes a link their team can open, search, and reason about.
What is this system?
AI coding agents keep their session history on the developer's own machine, in per-agent file formats. Traces turns those private, ephemeral files into a shared team resource. A command-line tool reads the local session files, cleans them of secrets, and uploads them to a hosted backend. A web app renders them as readable conversations under durable URLs. Around that core, the platform adds team accounts, visibility controls, automatic AI-generated summaries, git integration that links traces to the commits they produced, and a conversational assistant that can search and quote the accumulated trace library.
Who uses it
Developers share what their agent did and why — usually to give reviewers the reasoning behind a pull request. Teams organize traces under organizations, control who can see them, and export their data. Visitors browse a public catalog of traces without an account.
How data enters and leaves
Data enters primarily through the CLI, which uploads parsed agent sessions; through git hooks, which attach trace references to commits; and through OAuth logins (GitHub, Google), which create accounts. It leaves through the web app (profiles, a public catalog, a trace viewer), through pull-request comments posted by a GitHub App, through exports (JSON, Markdown, Hugging Face datasets), and through the agent assistant's streamed answers.
Central ideas, briefly
Everything orbits the trace: one recorded agent session with a stable public ID. Traces belong to a namespace — a personal account or an organization — and carry a visibility level that decides who may read them. After upload, an AI analysis pass derives a title and structured summary so libraries stay browsable at a glance. The word agent is overloaded in this system; the glossary untangles it.
How to read this explainer
The layers are ordered from concepts to implementation. Each page is a five to ten minute read and links to the next.
- Glossary — the vocabulary every later page uses.
- Domain model — the actors, records, and lifecycles, and who owns what.
- System architecture — the running parts, the stores, and the boundaries between them.
- Workflows — the primary read and write paths, step by step.
- Repository map — where each idea lives in the monorepo.